Fractional Time Support
It is important to understand that MusicMaster CS always handles times internally in milliseconds. To maintain the functionality of MusicMaster PRO and to not over complicate things for users that have no need for fractional times, MusicMaster CS defaults to just handling times to the nearest second.
MusicMaster CS has a setting in the UI that allows you to enable fractional runtimes if you need them. You can determine the subsecond divisions you wish to use, which can be a numeric value between 0 and 1000 where 0 indicates full seconds and 1000 indicates milliseconds. You can choose any value between these, meaning you can use values such as:
| Subsecond Division | Usage |
|
0 |
No fractions, just full seconds |
| 10 | Tenths of a second |
|
24 |
24 frames per second (for Film) |
| 25 | PAL 25 frames per second (for TV) |
| 30 | NTCS 30 frames per second (for TV) |
| 100 | Hundredths of a second |
| 1000 | Milliseconds |
This setting affects the way you enter times and the way they are shown in the UI, but storage is always in milliseconds, which also means that if you change this setting after you have already entered data, it will automatically adjust your data to the new precision. Times stored with higher precision that the UI display will be rounded accordingly.
There are four modes that can be used for handling fractional times, three ways that this feature can be enabled. It is fully supported across all Nexus functions that can be used to get and set time values. This allows for a great deal of flexibility in how Nexus enabled applications can use fractional times.
Nexus Fractional Time Modes
There are four modes:
Mode 0: No fractions (MM:SS)
This is the default mode and the way things have typically worked in MusicMaster PRO and MusicMaster CS for most clients. Times can only be entered to the nearest second. No fractions are used.
Mode 1: Fractions that use the subsecond division setting in MusicMaster (MM:SS.zzz)
This makes Nexus work like the MusicMaster CS US expecting data to be entered and shown using the number of subsecond divisions that is set in the UI, meaning that the user has the ability to change this setting at any time, and requires that a Nexus client have some awareness of that user setting, which can be checked via Nexus. It is only recommended to use this mode if your Nexusfunctionality is simply passing along time values as a string, without using them for calculations and when you are not importing new times to MusicMaster. For example, using the Nexus API to send data to a web page for display.
Mode 2: Fractions in milliseconds (MM:SS.fff)
This enables fractional runtimes for import and export in a consistent format with full milliseconds. Times are specified as MM:SS.fff where the fractional part is optional, but is always interpreted as milliseconds. This works fine even if the UI setting is a different precision, such as tenths of a second, as the UI will simply round the value to tenths when you are working in the UI. This mode is best when you want to use fractions, but don't want to be concerned about what the UI setting is and having to adapt to it. This also allows fractions to be used by the API even when they are not being used or shown at all in the UI.
Mode 3: Raw milliseconds (ffff)
This is similar Mode 2 in that times have millisecond precision and are not subject to the UI fractional time setting, but this allows API functions to specify timespan values in pure milliseconds, so instead of MM:SS.fff, you simply work with raw milliseconds that have no delimiters. For example, in this mode 3:00.500 is input and output as 180500. This formatting applies to Timespan fields and Runtime only. Date/Time and Time of Day fields will return with milliseconds, but will have the time portion formatted as HH:MM:SS.fff
Special note on localization: The Nexus API always handles time values that use separators without regard to the any regional or locale settings, meaning that the separator for time segments will always use a colon (:) to separate HH:MM:SS and a period (.) to separate any fractional time component. When using Raw Milliseconds, there are no delimiter characters used at all, except in the case of Date/Time values where we still use ISO format with milliseconds appended: YYYY-MM-DDTHH:MM:SS.fff
A word on formatting times for the API: We recommend that you format times to the full number of decimal places that the subsecond divisions you are using will output with. For example, if using milliseconds, then there are always 3 digits for the decimal portion of the time. These should be passed to the API as .000 through .999 with all three digits available. If you provide less digits than are required for the maximum number divisions, then the API will attempt to interpret what you mean, but this could result in mistakes. For example, an entry of 1:23.4 could be interpreted to mean 1:23.400 but will be interpreted as 1:23.004. The API will fill missing decimal places with leading zeros. If you always supply the entire value with appropriate leading and trailing zeros, this should never be a problem.
Enabling Fractional Times for Nexus
There are three ways to enable fractional time capabilities in Nexus.
The first is a new setting in the UI, which can be set separately for Enterprise and each station. This is done under Enterprise, Stations, where you edit the Station and set the Misc, SubSecond Divisions option. This defaults to MM:SS format, and allows selection of all four modes shown above. When set this way, it will automatically apply to all Nexus calls made by any Nexus Client application.
The second way is via the Nexus getStationProperty and setStationProperty commands. The new TIMEFORMAT property can be set to one of the mode values specified above (0-3). Once set, all Nexus calls made against the specified station will use the setting provided. This will also automatically apply to all Nexus calls made by any Nexus client application. An additional property has been added to these functions that allows you to reconfigure the subsecond division setting for Nexus in the case where you are using Mode 2. The new SUBSECONDDIVISIONS property can be set in the same manner as in the UI, with a value in the range (0-1000). Note that using these new station properties does not change these settings in the database or for the UI. These are simply set for the Nexus API where they can be changed at any time. They default initially to the settings from the UI and database and will revert to those when the server is restarted.
You can also set this property specifically on each Nexus call you make. If you do this, it will override the UI setting and give you complete control over how and when fractional times are used. This also lets you use different settings for different calls if you wish. To do this, you will add a new attribute to your mmRequest tags: timeFormat="X" where X is one of the mode values specified above (0-3). This is the recommended option when using this functionality. An important reason why this mode is recommended is because other applications may also be using Nexus, and this mode allows you complete control over every call you make, preventing changes made by users or other Nexus-enabled applications from interfering with your operations.
Sample Requests / Replies
If you do not wish to send fractional times to the API, there is no change to syntax if you use the UI properties or setStationProperty.
<mmRequest command="getSongInfo" station="One of Each" userData="testing"> <contents> <songList> <song songId="6608"/> </songList> </contents> </mmRequest>
<mmReply command="getSongInfo" version="1" station="One of Each" messageId="a2a81bae-d633-4776-b3f7-dd76074826ca" userData="testing" status="ok">
<contents>
<songList recordCount="1">
<song songId="6608" cutId="6608">
<field id="3" name="Category">A</field>
<field id="12" name="Run Time">1:23</field>
<field id="1" name="Song ID">6608</field>
<field id="106" name="Date">2025-05-05</field>
<field id="107" name="Time">05:55:55</field>
<field id="108" name="Length">1:23</field>
<field id="1194" name="DateTime">2025-02-28T09:50:00</field>
</song>
</songList>
</contents>
</mmReply>
Simply add the fractions to your time values. To use the recommended method of including the timeFormat attribute on your requests, you simply add that to the mmRequest tag as shown here:
<mmRequest command="getSongInfo" station="One of Each" userData="testing" timeFormat=”2” >
<contents>
<songList>
<song songId="6608"/>
</songList>
</contents>
</mmRequest>
<mmReply command="getSongInfo" version="1" station="One of Each" messageId="ea2cc722-3292-4c8b-b00f-ca10d86ec694" userData="testing" status="ok">
<contents>
<songList recordCount="1">
<song songId="6608" cutId="6608">
<field id="3" name="Category">A</field>
<field id="12" name="Run Time">1:23.654</field>
<field id="1" name="Song ID">6608</field>
<field id="106" name="Date">2025-05-05</field>
<field id="107" name="Time">05:55:55.999</field>
<field id="108" name="Length">1:23.456</field>
<field id="1194" name="DateTime">2025-02-28T09:50:00.777</field>
</song>
</songList>
</contents>
</mmReply>
Here it is using timeFormat 3 for pure milliseconds. As noted above, this only applies to timespan values like Runtime. In this mode, date and time of day values will still use normal formatting, but will always return the fraction in milliseconds:
<mmRequest command="getSongInfo" station="One of Each" userData="testing" timeFormat="3" >
<contents>
<songList>
<song songId="6608"/>
</songList>
</contents>
</mmRequest>
<mmReply command="getSongInfo" version="1" station="One of Each" messageId="3d1cdeb4-de1f-47a8-b404-17a8dadb4ccc" userData="testing" status="ok">
<contents>
<songList recordCount="1">
<song songId="6608" cutId="6608">
<field id="3" name="Category">A</field>
<field id="12" name="Run Time">83654</field>
<field id="1" name="Song ID">6608</field>
<field id="106" name="Date">2025-05-05</field>
<field id="107" name="Time">05:55:55.999</field>
<field id="108" name="Length">83456</field>
<field id="1194" name="DateTime">2025-02-28T09:50:00.777</field>
</song>
</songList>
</contents>
</mmReply>
The same applies to other functions. The syntax is unchanged. The only difference is the option addition of timeFormat in the mmRequest tag and the difference in how time values are formatted:
<mmRequest command="updateSongs" station="One of Each" userData="testing" timeFormat="2">
<contents>
<songList>
<song id="6608">
<field id="12">1:23.654</field>
<field id="108" name="Length">1:23.456</field>
<field id="1194" name="DateTime">2025-02-28T09:50:00.777</field>
<field id="107" name="Time">05:55:55.999</field>
</song>
</songList>
</contents>
</mmRequest>
Compatibility and Version Info
Available in MusicMaster CS 3.1.0.0 or later.